بازگشت

در این مقاله به توضیح روشی ساده و سریع برای مستند سازی در #C با استفاده از XML خواهیم پرداخت.(اگر شما آشنایی با مدارک XML ندارید می توانیداز اینجا توضیح ساده ای دراین باره بخوانید.)
توجه: اگر آشنایی چندانی با XML ندارید می توانید توضیحات مختصری در این باره را در اینجا بیابید.
توضیح های مستند در C‪#‬ برای هر کلاس، متود، فیلد یا اینترفیس قبل از آن نوشته می شود و بر خلاف کامنت های معمولی که با ‪"//"‬ تعریف می شوند مستند ها با علامت ‪"///"‬ ایجاد می شوند.
به منظور ایجاد مستند در C‪#‬ می توان از تگ های زیر برای رساندن مفاهیم خود استفاده کنید.
تگ های تعریف شده : MSDN
‏‪<‬c‪>‬
برای نمایش تکه کدهای تک خطی یا جهت قرار دادن نام اعضا در متن مورد استفاده قرار می گیرد. msdn
‏‪<‬code‪>‬
برای نمایش تکه کدهای چند خطی بکار میرود. msdn‬
‏‪<‬example‪>‬
برای نمایش مثال و نمونه کدی از کلاس، اینترفیس، متود یا فیلد مورد نظر بکار می رود. msdn
‏‪<‬exception‪>‬
بمنظور نمایش و اخطار برای اکشپشن هایی که ممکن است ایجاد شوند مورد استفاده قرار می گیرد. msdn
‏‪<‬include‪>‬
این تگ توضیحات موجود در فایل خارجی مشخص شده را نمایش می دهد. msdn
‏‪<list>‬
برای ایجاد لیست بکار می رود. msdn
‏<param>
برای مشخص کردن و توضیح در مورد یک پارامتر متود بکار می رود. msdn
‏<param name='name'>description</param>
‏‫name : نام پارامتر - ‏description: توضیحی در مورد پارامتر
‏<paramref>
برای نشان دادن یک پارامتر بکار می رود. msdn
‏<permission>
مشخص کننده ی سطح دسترسی است. msdn
‏<remarks>
برای نمایش توضیحات بکار می رود. msdn
‏‪<‬returns‪>‬
برای نمایش مقدار برگشتی یک عضو می باشد. msdn
‏‪<see>‬
‫ارجاع به مکانی دیگر که مرتبط می باشد. msdn
‏<summary>
خلاصه ای در مورد عضو می باشد. ویژال استودیو بصورت خودکار این تگ را هنگام تعریف مستند ایجاد می کند. msdn
‏‪<‬value‪>‬
این امکان را به شما می دهد تا در مقدار یا ارزش مورد یک خصوصیت (property) توضیح دهید. msdn

تولید مستند در Microsoft Visual Studio ‪.‬NET
پروژه ی C‪#‬ جدیدی از نوع Class Library بسازید و نام آن را XMLdoc بگذارید. سپس کد زیر را در کلاس وارد کنید.

using System;
namespace XMLdoc
{
 /// <summary>
 /// This project shows how to create XMl documentation in C#
 /// </summary>

 public class XMLdoc
 {
  /// <summary>
  /// m_iTestVar is a module level test variable for storing int 
  /// </summary>

  private int m_iTestVar;
  /// <summary>
  /// m_sTestVar is a module level test variable for storing string 
  /// </summary>

  private string m_sTestVar;
  /// <summary>
  /// XMLdoc is the constructor 
  /// </summary>

  public XMLdoc()
  {
   //
   // TODO: Add constructor logic here
   //
  }
  /// <summary>
  /// TestReturnBack is a test method which
 /// simply takes a name and returns it back.
  /// </summary>
  /// <param name="sName"></param>
  /// <returns></returns>

  public string TestReturnBack(string sName)
  {
   return "Your name is " + sName;
  }
 }
}

حال در بخش solution Explorer روی پروژه کلیک راست کرده روی Properties کلیک کنید.در پنجره ی باز شده در بخش Build مسیر خروجی برای فایل XML را مشخص کنید، در نهایت پروژه را کامپایل کنید و فایل XML مورد نظر در مسیر تعیین شده ایجاد می شود.
توجه: ویژوال C‪#‬ مستندات را به فرم XML ایجاد میکند(برخلاف جاوا که فایل HTML ایجاد می کند) و می توان از آن در هر جای دیگر که استفاده کرد.

نکته: اگر شما از ویژوال استودیو استفاده نمی کنید می توانید از این روش برای ایجاد فایل XML استفاده کنید، در زمان کامپایل تنها لازم است نام فایل خروجی را مشخص کنید یعنی به شکل زیر:

csc XMLdoc‪.‬cs ‪/‬doc‪:‬XMLdoc‪.‬xml

برای مشاهده ی این فایل می تونید از برنامه هایی مثل NDOC استفاده کنید، با استفاده از این برنامه می توانید فایل های مستند #C را به فرم HTML یا CHM در آورده و از آنها را در جای های مختلف مورد استفاده قرار دهید.

بن مایه ها:

http://www.codeproject.com/KB/cpp/TestXMLdoc.aspx
http://msdn.microsoft.com/en-us/library/b2s063f7(v=VS.80).aspx